///////////////////////////////////////////////////////////////////////
//                                                                   //
// KconfigSize : Linux kernel size and memory usage measurement tool //
//   Web interface setting and result data viewpoint          	     //
//                                                                   //
///////////////////////////////////////////////////////////////////////

Introduction
============================================================
KconfigWeb is the CGI script that presents the output result of KconfigSize tool 
by web interface. In this file, necessary items on how to use KconfigWeb are 
described as below. 
- pre-requisite
- KconfigWeb setting
- result data viewpoint


Pre-requisite 
============================================================
In order to run KconfigWeb, below conditions are necessary. 
- http server. need support CGI script. 
- Python
- GDChart library(libgdc) and  Python gdchart module


KconfigWeb setting
============================================================
(1) tool configuration file 
-----------------------

KconfigWeb configuration file is kconfigsize/conf/kconfigweb.conf

Each line has the format as following: 
<key>=<value>

Line which begins with "#" is treated as comment. 
Now explain each configurable key.

db_dir=<value>
------------------------------
  output result  directory of KconfigSize tool
   ex : db_dir=/home/foo/kc_db

(2) Notice
-----------------------
Among the CGI scripts provided by KconfigWeb, below three scripts are accessed 
directly by Web browser. 
  kconfigsize/bin/local/kconfigweb.cgi
  kconfigsize/bin/local/kconfigweb_bu.cgi
  kconfigsize/bin/local/kconfigweb_td.cgi

When create symbol link from public directory to CGI here, below must be 
attentioned: 
1) The names of symbol links must be the same as the CGI names. 
2) Three symbol links corresponding to CGI scripts must be put in the same 
   directory.

For example: 
<Good example>
 ln -s ~foo/kconfigsize/bin/local/kconfigweb.cgi \
     /usr/lib/cgi-bin/kconfigweb.cgi
 ln -s ~foo/kconfigsize/bin/local/kconfigweb_td.cgi \
     /usr/lib/cgi-bin/kconfigweb_td.cgi
 ln -s ~foo/kconfigsize/bin/local/kconfigweb_bu.cgi \
     /usr/lib/cgi-bin/kconfigweb_bu.cgi

<Bad example(1): the name of link is different from CGI name>
 ln -s ~foo/kconfigsize/bin/local/kconfigweb.cgi \
     /usr/lib/cgi-bin/kconfigweb_1.cgi
 ln -s ~foo/kconfigsize/bin/local/kconfigweb_td.cgi \
     /usr/lib/cgi-bin/kconfigweb_2.cgi
 ln -s ~foo/kconfigsize/bin/local/kconfigweb_bu.cgi \
     /usr/lib/cgi-bin/kconfigweb_3.cgi

< Bad example(2): symbol link files are put in different directory>
 ln -s ~foo/kconfigsize/bin/local/kconfigweb.cgi \
     /usr/lib/cgi-bin/kconfigweb.cgi
 ln -s ~foo/kconfigsize/bin/local/kconfigweb_td.cgi \
     /usr/lib/cgi-bin/kcw/kconfigweb_td.cgi
 ln -s ~foo/kconfigsize/bin/local/kconfigweb_bu.cgi \
     /usr/lib/cgi-bin/kcw/kconfigweb_bu.cgi


Result data viewpoint
============================================================
(1) Top page
-----------------------
Top page of KconfigWeb is shown by access kconfigweb.cgi. In this page, there 
are two links named [bottom-up] and [top-down]. 
If [bottom-up] link is clicked, then result page of bottom-up approach will show. 
If [top-down] link is clicked,then result page of top-down approach will show. 
For the difference between bottom-up and top-down, please refer to 
configure_en.txt.

(2) Result of bottom-up approach
-----------------------
In [Examined conditions] table, implemented measurement list is presented. 
Choose the config item category in list box of [Category] and click [Show] 
button, the result based on the selected conditions is showed. 

In [Comparison between two conditions], two measurement result can be compared. 
Select measurement result from the pull-down menu of [source][target], then 
select the config item category from list box and click [compare] button. 

In [Data trend], use line graph to show the change trend of data among more 
than two kernels. Select the measurement result from list box, and then select 
data items from pull down menu, and finally click [show] button. 

Term definitions on presentation-item-selections and graph-titles are described 
below. 

--- Base kernel
The kernel built from the .config file, whose all enabled (CONFIG_*=y) config
items are marked as [=b] in target-config-item list.
Please refer to configure_en.txt. 

--- Raw data
Just means measurement data. 
if size is specified, it refers to kernel image size, if memory is specified, 
it refers to the value of memory usage(total, used, free).

--- Total impact
When a target config item is enabled(CNOFIG_*=y), the excess of kernel image 
size and/or memory uage.  For example, total impact of CONFIG_A size is the 
size of kernel built with CONFIG_A=y minus the size of base kernel. 

--- Isolated impact
When generating .config file for a target config item, KconfigSize tool will 
automatically enable all config items which the target config item depends on.
So total impact also includes the contribution introduced by config items
which the target config item depends on.
KconfigSize tool will exclude those contribution and try to calculate the impact
exclusively introduced by the target config item, so-called "Isolated impact".
The calculation method is as below: 

For example, target config item is CONFIG_X, and CONFIG_X depdends on CONFIG_Y.
KconfigSize tool will automatically handle the dependency problem. CONFIG_X 
and CONFIG_Y are all set to =y and .config file for CONFIG_X is generated and
kernel is made. If CONFIG_Y is also specified as a target-config-item in the
target-config-item list, .config file for CONFIG_Y(CONFIG_X=n, CONFIG_Y=y) is 
also generated. Then KconfigSize tool will subtract the size of the kernel for
CONFIG_Y from the size of the kernel for CONFIG_X. The balance is the
[isolated impact] of CONFIG_X. 

KconfigSize tool will try its best to calculate the isolated impact of target-
config-item. However, if CONFIG_Y is not specified as target-config-item, the 
[isolated impact] of CONFIG_X can not be calculated. Under such circumstances, 
[CONFIG_X+CONFIG_Y] is recorded in the field of isolated impact for CONFIG_X.
The value is the balance between CONFIG_X kernel and base kernel = total impact.


(3) Result of Top-down approach
-----------------------
The way to view the result from Top-down approach is almost the same as that of
Bottom-up approach except below. 
In Top-down approach, isolated impact can not be calculated. So for a target 
config item, there is just [impact].


Other
============================================================
KconfigWeb is based on Bloatwatch created by Matt Mackall. For Bloatwatch, 
please refer to http://selenic.com/repo/bloatwatch



